home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-17 / qdpmizip.zip / QDPMIZIP.EXE / QDPMI.DOC < prev    next >
Text File  |  1992-08-04  |  22KB  |  542 lines
  1.   =========================================================================
  2.                           Quarterdeck Office Systems
  3.                                QDPMI Host V1.0
  4.  
  5.   =========================================================================
  6.   NOTICE TO END USERS: THIS SOFTWARE MAY BE FREELY COPIED, HOWEVER YOUR
  7.   ACTUAL USE OF QDPMI IS CONDITIONED UPON (i) YOUR POSSESSION OF AN
  8.   AUTHORIZED COPY OF QEMM-386 AND (ii) YOUR COMPLIANCE WITH THE TERMS OF
  9.   THE QEMM-386 QUARTERDECK END USER LICENSE AGREEMENT, WHICH GOVERNS USE OF
  10.   THIS SOFTWARE.
  11.  
  12.   Copyright (c) Quarterdeck Office Systems, Inc. 1986-1992.  ALL RIGHTS
  13.   RESERVED.  DOS Extension Technology by ERGO Computing, Inc. Copyright (c)
  14.   1991-1992.  ALL RIGHTS RESERVED.
  15.   =========================================================================
  16.  
  17.  
  18. INTRODUCTION
  19. ------------
  20.  
  21. The Quarterdeck DPMI Host (QDPMI) is a companion product to the Quarterdeck 
  22. Expanded Memory Manager-386 (QEMM-386). It is a full implementation of 
  23. Version 0.9 of the DOS Protected Mode Interface (DPMI) specification, 
  24. including MS-DOS extensions and virtual memory.
  25.  
  26. DPMI is an emerging industry standard for allowing DOS applications
  27. to access the protected mode features of the 80386 and 80486 processors.
  28. To DOS application users this means that an application can now be
  29. larger and more full featured than those applications restricted to
  30. 640K.
  31.  
  32. The DPMI specification was developed by a consortium of computer companies,
  33. including Quarterdeck, Borland, Ergo, IBM, Intel, Intelligent Graphics,
  34. Locus, Lotus Development, Microsoft, Phar Lap, Phoenix Technologies
  35. and Rational Systems.
  36.  
  37. Protected mode multitasking environments, memory managers, or operating
  38. systems that implement DPMI functions are called DPMI hosts. Protected
  39. mode applications that request DPMI functions (directly or indirectly)
  40. are called DPMI clients.
  41.  
  42. DOS applications using DPMI (DPMI clients) can run in a variety of
  43. operating environments, including DOS, DR DOS, Microsoft Windows,
  44. OS/2, 386-based UNIX, DESQview 386 and DESQview/X provided a
  45. DPMI host is present.
  46.  
  47. The Quarterdeck DPMI Host (QDPMI) provides mode-switching and extended
  48. memory management to DPMI clients. It runs at a more privileged level
  49. than its clients and uses the hardware to enforce a supervisor/user
  50. protection model. This allows QDPMI to support centralized virtual
  51. memory and maintain full control over client programs' address spaces
  52. and access to hardware.
  53.  
  54. Users of Quarterdeck's DESQview 386 or DESQview/X can run multiple QDPMI 
  55. clients simultaneously, each optionally having its own virtual memory.
  56.  
  57.  
  58. Software Compatibility
  59. ----------------------
  60.  
  61. DOS applications that support the DPMI specification are just coming
  62. to market. The earliest of these are programmer's tools including 
  63. Microsoft's C/C++ Development System for Windows (version 7), Borland's C++ 
  64. (version 3) and Intel's Code Builder Kit (version 1.1). QDPMI is compatible 
  65. with the above programs.
  66.  
  67. Microsoft Windows version 3.1 includes its own DPMI host. When QDPMI
  68. sees Windows star tup, it steps aside letting Windows provide the DPMI 
  69. services for programs running in its environment.
  70.  
  71.  
  72. About This Manual
  73. -----------------
  74.  
  75. This manual is your reference guide to the Quarterdeck DPMI Host (QDPMI). 
  76. This manual tells you:
  77.  
  78.      o    How to install QDPMI.
  79.  
  80.      o    How to specify whether virtual memory is to be used and the amount 
  81.           of virtual memory to be reserved.
  82.  
  83.      o    About the command line parameters available with QDPMI.
  84.  
  85. The Quarterdeck DPMI Host (QDPMI) requires the Quarterdeck Expanded
  86. Memory Manager (QEMM-386) for its services to be made available to
  87. DPMI client programs. So before you install QDPMI, please check that
  88. QEMM-386 is either installed or available to be installed on your
  89. system.
  90.  
  91. Installing QDPMI is easy. All you must do is run the QDPMI installation
  92. program, INSTALL.
  93.  
  94. During installation, INSTALL will display several screens, either
  95. to ask for information or to inform you of its progress. If QEMM-386 is not 
  96. currently installed in your system, INSTALL will post a warning message, 
  97. telling you that QEMM-386 was not found in your CONFIG.SYS file and telling 
  98. you to install it. As mentioned earlier, QDPMI will not work without QEMM-
  99. 386.
  100.  
  101. INSTALL will need to know where to copy QDPMI files. The default drive and 
  102. directory is the same as that used by QEMM-386 (usually C:\QEMM). Next 
  103. INSTALL will ask you whether you would like QDPMI to provide virtual memory 
  104. support for each DPMI client you run. If you answer Yes, you must then 
  105. indicate how much disk space should be allocated for the virtual memory swap 
  106. file. The default is 1024K per DPMI client.
  107.  
  108. When QDPMI uses virtual memory, it creates a virtual memory swap file.
  109. INSTALL next asks you whether QDPMI should automatically delete the
  110. virtual memory swap file when your application terminates. Creating and 
  111. deleting the virtual memory swap file takes more time, but conserves disk 
  112. space. 
  113.  
  114. When you have answered the above questions, INSTALL automatically
  115. creates the necessary change to your AUTOEXEC.BAT and CONFIG.SYS files 
  116. needed by DOS to load QDPMI, and offers to modify these files for you. Then 
  117. it copies the QDPMI files to the drive and directory you indicated.
  118.  
  119.  
  120. Installing QDPMI from floppy
  121. ----------------------------
  122.  
  123. To install QDPMI from the QDPMI diskette:
  124.  
  125. Place the QDPMI disk in drive A.
  126.  
  127. Type A:INSTALL and press Enter.
  128.  
  129.  
  130. Installing QDPMI by downloading from the Quarterdeck BBS
  131. --------------------------------------------------------
  132.  
  133. If you have downloaded the QDPMI files from a Quarterdeck bulletin
  134. board into a drive/directory on your hard disk:
  135.  
  136. Change to the drive and directory where the QDPMIZIP.EXE file you
  137. downloaded from the bulletin board is stored.
  138.  
  139. Type QDPMIZIP and press Enter.
  140.  
  141.      NOTE: QDPMIZIP.EXE is a self-extracting zip file that when run will 
  142.            extract three files, INSTALL.EXE, LICENSE.TXT, and QDPMI.QIP
  143.            into the current directory.
  144.  
  145. Now type INSTALL and press Enter.
  146.  
  147.  
  148. QDPMI Installation Program
  149. --------------------------
  150.  
  151.      NOTE: If you have an LCD or Gas Plasma display, as on some laptops, or 
  152.            a monochrome monitor, we recommend that you run INSTALL in 
  153.            mononchrome mode by typing X:INSTALL/m (where X: is the drive and 
  154.            directory containg the QDPMI files.
  155.  
  156. Follow the instructions on the screen. INSTALL copies the QDPMI files
  157. to your hard disk and configures QDPMI.
  158.  
  159. It is always a good idea when making changes to your system configuration
  160. to run QEMM-386's Optimize program after making your changes. This
  161. will insure the best use of your system's memory.
  162.  
  163. After successfully completing the QDPMI installation procedure, it
  164. will be necessary to reboot your system to begin using QDPMI.
  165.  
  166. If you want to check that DPMI is working, typing QDPMI at the DOS command 
  167. line without any parameters will display the current status of QDPMI.
  168.  
  169. That's all there is to installing QDPMI.
  170.  
  171.  
  172. Installation Notes
  173. ------------------
  174.  
  175.  
  176. QDPMI Client Initialization with Virtual Memory
  177. -----------------------------------------------
  178.  
  179. At DPMI client initialization time (when an application that requires
  180. DPMI services is run), QDPMI will attempt to create the virtual memory
  181. swap file whose name and size appear in the QDPMI environment variable.
  182. If the swap file name is not specified in the QDPMI environment variable,
  183. the file will be opened or created in the directory from which QDPMI.SYS
  184. was loaded at system startup, with the base name of QDPMI.SWP.
  185.  
  186. If the swap file size is not specified, QDPMI will create the file
  187. with a default size of 2 Megabytes.
  188.  
  189. If the swap file exists, it will be used. Its existing size will be
  190. modified to equal the user specified value.
  191.  
  192. If the KILLSWAP option is specified, QDPMI will delete the virtual
  193. memory swap file upon the termination of the DPMI client application.
  194.  
  195. In multitasking environments such as DESQview and DESQview/X, each task or 
  196. DESQview window can have its own unique set of QDPMI switches and QDPMI 
  197. environment variable options in force.
  198.  
  199. It is necessary that each simultaneously executing DPMI client application 
  200. utilizing virtual memory have its own unique virtual memory swap file. The 
  201. name of the swap file that is provided in the QDPMI environment variable is 
  202. therefore modified by QDPMI before it is opened or created, by appending a 
  203. digit to the end of its base name. For example: QDPMI.SWP would become 
  204. QDPMI0.SWP, and QDPMISWP.SWP would become QDPMISW0.SWP. The actual digit 
  205. will vary depending on whether DESQview is active or not, and how many other 
  206. DPMI clients are active in other DOS partitions.
  207.  
  208. If for some reason QDPMI cannot find or create its virtual memory swapfile, 
  209. it will issue a message and disable the virtual memory feature for the 
  210. current client's invocation. Causes for this may be:
  211.  
  212.      o    Insufficient disk space.
  213.  
  214.      o    Improperly specified Swap File name (QDPMI environment variable).
  215.  
  216.      o    Non-existent directory specified.
  217.  
  218.  
  219. System Interrupt Stack Configuration
  220. ------------------------------------
  221.  
  222. It is important for some applications that a line exist in CONFIG.SYS 
  223. setting up system interrupt stack configuration. The suggested values are:
  224.  
  225.      stacks = 9,256
  226.  
  227. This means that DOS should allocate nine system stacks, each 256 bytes in 
  228. size.
  229.  
  230. The default for this setting is:
  231.  
  232.      stacks = 9,128
  233.  
  234. Under QDPMI, this may not be sufficient.
  235.  
  236.  
  237. Novell Netware
  238. --------------
  239.  
  240. QDPMI has the capability to support either 16 or 32 bit DPMI clients.
  241. When a 32 bit client is executing, it expects all 32 bits of the processor's
  242. 32 bit registers to be preserved across interrupts. There are some device 
  243. drivers and TSRs that utilize the 80x86's 32 bit registers, but do not 
  244. preserve them, causing undesirable erratic behavior of 32 bit DPMI clients. 
  245. A notable example is Novell's LAN WorkPlace for DOS v4.01 (TCPIP.EXE). 
  246. Running the supplied TSR program LWPFIX.COM after loading the LAN WorkPlace 
  247. TCPIP driver will prevent this erratic behavior.
  248.  
  249.      NOTE: Novell has addressed this problem, and later releases will have 
  250.            the appropriate corrections.
  251.  
  252.  
  253. QDPMI Reference
  254. ---------------
  255.  
  256. This chapter is the reference guide for command line parameters used
  257. with both QDPMI.SYS as well as QDPMI.COM programs. This chapter also
  258. explains the way to use the QDPMI environment variable to further
  259. control QDMPI's behavior.
  260.  
  261.  
  262. QDPMI Command Line Parameters
  263. -----------------------------
  264.  
  265. Both QDPMI.SYS and QDPMI.COM respond to the same set of command line
  266. parameters. Command line parameters may be used on the QDPMI device
  267. driver line in CONFIG.SYS to initially set QDPMI's options.  QDPMI.COM
  268. may also be used to modify any or all QDPMI's options at a later time.
  269.  
  270. To use a QDPMI.SYS command line parameter you type the parameter name on the 
  271. same line as DEVICE=C:\QEMM\QDPMI.SYS in your CONFIG.SYS file. To use a 
  272. QDPMI.COM command line parameter you type the parameter name after QDPMI at 
  273. the DOS prompt. You may use an abbreviation instead of the parameter name. 
  274. The abbreviation for each QDPMI command line parameter is shown below in 
  275. parentheses after each parameter name.
  276.  
  277.  
  278. The QDPMI command line parameters are:
  279.  
  280.      DPMI     (ON)     turns DPMI 0.9 services on. This is a default 
  281.                        setting.
  282.  
  283.      NODPMI   (OFF)    turns DPMI services off.
  284.  
  285.      VMON     (VM)     turns QDPMI virtual memory on. This is the default 
  286.                        setting.
  287.  
  288.      VMOFF    (NOVM)   turns QDPMI virtual memory off.
  289.  
  290.      KILLSWAP (KLSW)   causes the QDPMI host to delete its virtual memory 
  291.                        swap file at the termination of the DPMI client 
  292.                        application. This is the default setting.
  293.  
  294.      KEEPSWAP (KPSW)   causes the QDPMI host not to delete its virtual 
  295.                        memory swap file at the termination of the DPMI 
  296.                        client application.
  297.  
  298.      EXTCHKON (XCHK)   causes the QDPMI host to step out of the way for 
  299.                        incompatible DOS extenders that prefer to do all of 
  300.                        their own DOS extender work in their own way. This is 
  301.                        the default setting.
  302.  
  303.      EXTCHOFF (NOXCHK) causes the QDPMI host not to step out of the way for 
  304.                        incompatible DOS extenders that prefer to do all of 
  305.                        their own DOS extender work in their own way.
  306.  
  307.  
  308. The QDPMI Environment Variable
  309. ------------------------------
  310.  
  311. QDPMI looks at an environment variable to determine information regarding
  312. its configuration. The environment variable is QDPMI. Its syntax is
  313. as follows:
  314.  
  315. SET QDPMI=[MAXLOW <aaaa>] [MINMEM <bbbb>] [MAXMEM <cccc>] [SWAPFILE 
  316. <filename> [dddd]]
  317.  
  318.      NOTE: The environment variable line must appear in your AUTOEXEC.BAT 
  319.            file as one line.
  320.  
  321. The QDPMI environment variable is not required to be set for QDPMI's 
  322. services to be utilized. QDPMI will use a set of default values in the 
  323. absence of user specified ones. All individual parameters within the QDPMI 
  324. environment variable are also optional, and may be specified in any order. 
  325. Each individual parameter group specified MUST be complete within itself, 
  326. however.
  327.  
  328. MAXMEM <cccc>  is the maximum number of kilobytes of physical memory that 
  329.                will be reserved by QDPMI. This can be any number up to the 
  330.                amount of physical memory available on your system, and 
  331.                will be allocated from VCPI, XMS, extended, and conventional 
  332.                memory resources, in that order. The memory used by QDPMI 
  333.                includes all memory for use by its code, data, and page 
  334.                tables, as well as memory requested for use by the DPMI 
  335.                client application. If MAXMEM is greater than the available 
  336.                physical memory, or greater than external limits placed on 
  337.                extended memory resources by multitaskers such as DESQview, 
  338.                MAXMEM will be adjusted downward to be within those limits. 
  339.                The default value is system max. If omitted or explicitly set 
  340.                to zero, MAXMEM is set to the largest value supported on your 
  341.                system. This will either be the size of all of your physical 
  342.                memory, or that which is available to the current partition 
  343.                of DESQview, whichever is smaller.
  344.  
  345. MINMEM <bbbb>  is the amount of physical memory in kilobytes that will be 
  346.                reserved by QDPMI immediately upon DPMI client application 
  347.                initialization. MAXMEM must be greater than or equal to 
  348.                MINMEM. If this is not the case, QDPMI will set the value 
  349.                of MAXMEM to equal that of MINMEM. The difference between 
  350.                MAXMEM and MINMEM is the amount of memory that will be 
  351.                managed dynamically by QDPMI, and made available to other 
  352.                applications (including other DPMI clients) when freed. This 
  353.                dynamic memory pool is managed through the use of VCPI memory 
  354.                only. The default value for MINMEM varies depending on the 
  355.                amount of physical memory installed in your computer. Its 
  356.                lowest possible value is 140 kilobytes. Any attempt to 
  357.                set MINMEM to a lower value will be ignored, and this minimum 
  358.                will be used. If unspecified, MINMEM will also be set to this 
  359.                minimum value.
  360.  
  361. MAXLOW <aaaa>  is the maximum number of kilobytes of conventional DOS memory 
  362.                allowed to be reserved by QDPMI for use as its memory 
  363.                resources. Setting it to any non-zero value will allow QDPMI 
  364.                to allocate DOS conventional memory for use in its memory 
  365.                pool. Note that QDPMI will only resort to using DOS 
  366.                conventional memory if expanded and extended memory resources 
  367.                are insufficient to satisfy the MINMEM request. The default 
  368.                value is 0. Conventional memory is only used if MINMEM cannot 
  369.                be satisfied from other resources, and only if this value is 
  370.                non-zero.
  371.  
  372. SWAPFILE <filename> [<dddd>] is the base name of the virtual memory swapfile 
  373.                that QDPMI will use, optionally followed by its size in 
  374.                kilobytes. The size of the virtual memory swapfile that you 
  375.                specify may be any value up to 64 megabytes or the size of 
  376.                the free space available on your hard disk. Be aware, 
  377.                however, that at DPMI client initialization, a fixed size 
  378.                file will be created that is the FULL SIZE that you have 
  379.                requested. The default base filename is QDPMI.SWP. Its 
  380.                default size is 2MB.
  381.  
  382.  
  383. Virtual Memory Total Memory Size
  384. --------------------------------
  385.  
  386. The SUM of the value of MAXMEM and the size of the virtual swapfile is the 
  387. amount of virtual memory (in kilobytes) available to QDPMI client 
  388. applications when the virtual memory option is enabled.
  389.  
  390.  
  391. Error Messages
  392. --------------
  393.  
  394. QDPMI will display error messages when trying to load QDPMI, when
  395. trying to initialize a DPMI client. In addition, error messages may
  396. also be generated by the QDPMI kernel or the DOS extender.
  397.  
  398.  
  399. QDPMI.COM error messages are as follows:
  400. ----------------------------------------
  401.  
  402. QDPMI: Client already active -- Cannot modify parameters.
  403.      A DPMI client has spawned COMMAND.COM, and is still active in the 
  404.      current DOS partition. It is inappropriate to change QDPMI parameters 
  405.      while the QDPMI host is currently active.
  406.  
  407. QDPMI: Already supported -- Not reloaded.
  408.      Another DPMI Host other than Quarterdeck's has been detected. 
  409.      Quarterdeck's QDPMI is not loaded.
  410.  
  411. QDPMI: Version incompatibility error -- Re-install or use same version.
  412.      This message only appears if the device driver QDPMI.SYS and the 
  413.      utility program QDPMI.COM are not the same version. This is an error in 
  414.      installation or updating. You must re-install QDPMI.
  415.  
  416. QDPMI: Cannot locate QEMM386.SYS Memory Manager -- Not loaded.
  417.      Quarterdeck's QDPMI Host will only function in conjunction with 
  418.      Quarterdeck's QEMM-386 Memory Manager.
  419.  
  420. QDPMI: Error accessing XDI -- Not loaded.
  421.      The QDPMI Host has encountered an error initializing its XDI interface 
  422.      and cannot load.
  423.  
  424. QDPMI: Too Many DPMI Processes -- Not loaded.
  425.      The QDPMI Host has the capability of supporting up to 15 concurrent 
  426.      processes under DESQview. If there are more than 15 windows on the 
  427.      screen, and a DPMI client is started in the 16th or higher window, the 
  428.      DPMI client will fail to initialize, and QDPMI.COM will display this 
  429.      message if run in this window.
  430.  
  431. QDPMI: Overlay File Path/Name is too long.
  432.      The QDPMIVM.OVL files (and their paths) are too long. Use a path less 
  433.      removed from the root.
  434.  
  435. QDPMI: Quarterdeck QDPMI Host is not resident.
  436.      QDPMI.COM issues this message if run without having previously loaded 
  437.      QDPMI.SYS in CONFIG.SYS.
  438.  
  439.  
  440. QDPMI client initialization messages are as follows:
  441. ----------------------------------------------------
  442.  
  443. QDPMI: Open Error.
  444.      QDPMI could not open its overlay file QDPMIVM.OVL. You should make sure 
  445.      that it is in the same directory as QDPMI.SYS.
  446.  
  447. QDPMI: Processor Error.
  448.      QDPMI must have an 80386 or later processor in order to run.
  449.  
  450. QDPMI: Read Error.
  451.      QDPMI cannot read its overlay file QDPMIVM.OVL.
  452.  
  453. QDPMI: Seek Error.
  454.      QDPMI can not seek in its overlay file QDPMIVM.OVL.
  455.  
  456. QDPMI: Close Error.
  457.      QDPMI can not close its overlay file QDPMIVM.OVL.
  458.  
  459. QDPMI: Bad .OVL Error.
  460.      QDPMIVM.OVL file is corrupted.
  461.  
  462. QDPMI: Exec Error.
  463.      QDPMI could not transfer control to its overlay.
  464.  
  465. QDPMI: Init Error.
  466.      QDPMIVM.OVL could not complete its initialization.
  467.  
  468. QDPMI: Mode Error.
  469.      The QDPMI client is attempting to re-initialize the QDPMI Host in 
  470.      another mode (16/32 bit) than it was originally initialized.
  471.  
  472. QDPMI: Task Error.
  473.      The maximum of 15 simultaneous DPMI clients are already running in 
  474.      other DESQview windows.
  475.  
  476. QDPMI: Version Error.
  477.      There is a discrepancy between the QDPMI version of the device driver 
  478.      (QDPMI.SYS), and the kernel (QDPMIVM.OVL).
  479.  
  480.  
  481. QDPMI Kernel error messages are as follows:
  482. -------------------------------------------
  483.  
  484. QDPMI Warning: User requested memory (XXXXH K) too small Using minimum: 
  485. YYYYH.
  486.  
  487. QDPMI: Invalid exception number
  488.  
  489. QDPMI: No ring 3 stack found
  490.  
  491. QDPMI: Insufficient stack space to process  software int
  492.  
  493. QDPMI: No User Handler for interrupt
  494.  
  495. QDPMI: Kernel issued software int!
  496.  
  497. QDPMI: Illegal value in chain thunk: Exiting
  498.  
  499. QDPMI: Cannot find expected free page
  500.  
  501. QDPMI: Cannot allocate system stack
  502.  
  503. QDPMI: No temporary GDT selectors available
  504.  
  505. QDPMI: Illegal Real Mode Call Back number
  506.  
  507. QDPMI: Bad free swap page pointer
  508.  
  509. QDPMI: Cannot grow memory pool
  510.  
  511. QDPMI: No pages available in swap file
  512.  
  513. QDPMI: No pages available for swap-in
  514.  
  515. QDPMI: Error writing swap file
  516.  
  517. QDPMI: Error reading swap file
  518.  
  519.  
  520. DOS EXTENDER error messages are as follows:
  521. -------------------------------------------
  522.  
  523. DosX: Bad function called
  524.  
  525. DosX: Function not supported
  526.  
  527. DosX: Undefined DOS function
  528.  
  529. DosX: Real mode interrupt failed
  530.  
  531. DosX: Failed to Allocate real mode call back address
  532.  
  533. DosX: Int 33h fxn 15h has not been called
  534.  
  535. DosX: Cannot allocate buffer
  536.  
  537. DosX: Failed to copy data to real mode buffer
  538.  
  539. DosX: Failure calling real mode
  540.  
  541. 
  542.